DigiLocker Fetch Document API

The following document highlights the details of the DigiLocker Fetch Document API.

API Description

Objective

The DigiLocker Fetch Document API retrieves documents from DigiLocker. For the documents that are non-issued, the API issues them before returning the document data.

Input	Output
Document parameters required for retrieving documents from DigiLocker. These parameters are retrieved from the DigiLocker Pull Parameters API responses.	The requested documents with their associated data from DigiLocker

API URL

https://ind-verify.hyperverge.co/api/digilocker/fetchDocuments

API Endpoint

fetchDocuments

Overview

The DigiLocker Fetch Document API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Method - POST

Authentication

You need a unique pair of application ID ( appId ) and application key ( appKey ) from HyperVerge to verify your identity for accessing the API.

Headers

Header	Mandatory / Optional	Description	Input Format
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
transactionId	Optional	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Inputs

The following tables provide the details of the parameters required for the DigiLocker Fetch Document API's request body. Depending on the type of document being retrieved, the parameters are categorised into the following two groups:

Issued Documents

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
referenceId	Mandatory	string	The parameter that represents the unique reference identifier generated in the initial request	Not Applicable	Not Applicable
docs	Mandatory	array	The parameter that contains the collection of document parameters	Not Applicable	Not Applicable
docs.uri	Mandatory	string	The parameter that specifies the unique URI for every document. This can be received from the fetch issued document API	Not Applicable	Not Applicable
docs.file	Optional	string	The parameter that indicates if the document is needed in file format. When set to yes, an s3 url with a validity of 15 minutes will be returned	yes / no	Not Applicable
useUpstreamStatus	Optional	string	The parameter that controls whether the API returns a failure response (with status code 504) when it fails to retrieve all the documents specified in the request. When set to "yes", the API returns a failure response	yes / no	Not Applicable
returnAllFieldsFromDigilocker	Optional	string	The parameter that controls whether the API retrieves all the fields for PAN and DL from the DigiLocker account	yes / no	Not Applicable
useV2StorageLocation	Optional	string	The parameter that enables dashboard visibility. When set to "yes", you can view the data in the dashboard	yes / no	no

Non-Issued Documents

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
referenceId	Mandatory	string	The parameter that represents the unique reference identifier created for the Initial DigiLocker request	The same referenceId value used as an input to the DigiLocker Consent URL API	Not Applicable
docs	Mandatory	array	The parameter that contains the collection of document parameters	Not Applicable	Not Applicable
docs.docId	Mandatory	string	The parameter that specifies the OrgId and docType	The format of the input should be orgId_docType. For example, "000027_SSCER" where OrgId:000027 and docType:SSCER	Not Applicable
docs.file	Mandatory	string	The parameter that indicates if the document is available	yes / no	Not Applicable
docs.params	Mandatory	object	The parameter that contains the parameters and their associated values received from the DigiLocker Pull Parameters API required for retrieving the user's document from DigiLocker. Non-Issued PAN PANFullName is now an optional parameter while retrieving a non-issued PAN. ( According to a DigiLocker release on 21st June 2024, the name reflected on the user's DigiLocker profile will be automatically considered during the retrieval process )	Not Applicable	Not Applicable
useUpstreamStatus	Optional	string	The parameter that controls whether the API returns a failure response (with status code 504) when it fails to retrieve all the documents specified in the request. When set to "yes", the API returns a failure response	yes / no	Not Applicable

Request

The following code snippet demonstrates standard curl requests for the DigiLocker Fetch Document API:

Retrieve Issued Documents

curl --location --request POST 'https://ind-verify.hyperverge.co/api/digilocker/fetchDocuments' \
--header 'appid: <appId-shared-by-HyperVerge>' \
--header 'appKey: <appKey-shared-by-HyperVerge>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "referenceId": "test-fetch-id",
    "docs": [
      {
        "uri": "in.gov.cbse-SSCER-1234",
        "file": "no"
      }
    ]
}'

Retrieve Non-Issued Documents

curl --location --request POST 'https://ind-verify.hyperverge.co/api/digilocker/fetchDocuments' \
--header 'appid: <appId-shared-by-HyperVerge>' \
--header 'appKey: <appKey-shared-by-HyperVerge>' \
--header 'Content-Type: application/json' \
--data-raw '{
"referenceId": "test-fetch",
"docs": [
{
  "docId": "000027_SSCER",
  "file": "yes",
  "params": {
      "year": "2008",
      "rollno": "123456"
  }
},
{
  "docId": "001891_PANCR",
  "file": "yes",
  "params": {
    "panno": "ABCD123ABC"
  }
}
]   
}'

Retrieve Both Issued and Non-Issued Documents

curl --location --request POST 'https://ind-verify.hyperverge.co/api/digilocker/fetchDocuments' \
--header 'appid: <appId-shared-by-HyperVerge>' \
--header 'appKey: <appKey-shared-by-HyperVerge>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "referenceId": "test-fetch-id",
    "docs": [
        {
            "uri": "in.gov.cbse-SSCER-1234",
            "file": "no"
        },
        {
            "docId": "001891_PANCR",
            "file": "yes",
            "params": {
                "panno": "ABCD123ABC"
            }
        }
    ]
}'

Success Response

The following code snippet demonstrates success responses from the DigiLocker Fetch Document API:

Issued Documents

{
  "status": "success",
  "statusCode": "200",
  "result": [
    {
      "uri": "in.gov.cbse-SSCER-53969032016",
      "data": {
        "number": "123456",
        "name": "John Doe",
        "dob": "01-02-93",
        "address": "permanent, IN",
        "photo": "",
        "file": "https://example.com"
      }
    }
  ]
}

Non-Issued Documents

{
  "status": "success",
  "statusCode": "200",
  "result": [
      {
          "docId": "000027_SSCER",
          "data": {
              "number": "123456",
              "name": "John Doe",
              "dob": "01-02-93",
              "address": "permanent, IN",
              "photo": "",
              "file": "https://example.com"
          }
      },
      {
          "docId": "001891_PANCR",
          "data": {
              "number": "ABCD123EF",
              "name": "John Doe",
              "dob": "01-02-93",
              "address": "permanent, IN",
              "photo": "",
              "file": "https://example.com"
          }
      }
  ]
}

Both Type of Documents

{
  "status": "success",
  "statusCode": "200",
  "result": [
    {
      "uri": "in.gov.cbse-SSCER-53969032016",
      "data": {
        "number": "123456",
        "name": "John Doe",
        "dob": "01-02-93",
        "address": "permanent, IN",
        "photo": "",
        "file": "https://example.com"
      }
    },
    {
      "docId": "001891_PANCR",
      "data": {
        "number": "ABCD123EF",
        "name": "John Doe",
        "dob": "01-02-93",
        "address": "permanent, IN",
        "photo": "",
        "file": "https://example.com"
      }
    }
  ]
}

Success Response Details

The following table outlines the details of the success response from the DigiLocker Fetch Document API:

Parameter	Type	Description
status	string	The status of the request
statusCode	string	The HTTP status code for the response
result	array	An array of objects, each containing document data
result[].uri	string	The unique URI for issued documents (present for issued documents only)
result[].docId	string	The document ID for non-issued documents (present for non-issued documents only)
result[].data	object	An object containing the document data including number, name, dob, address, photo, and file URL
result[].data.number	string	The document number
result[].data.name	string	The name associated with the document
result[].data.dob	string	The date of birth associated with the document
result[].data.address	string	The address associated with the document
result[].data.photo	string	The photo URL or data associated with the document
result[].data.file	string	The file URL for the document

Error Responses

The following are some error responses from the DigiLocker Fetch Document API:

Document Not Found

{
  "status": "success",
  "statusCode": "200",
  "result": [
      {
          "docId": "000027_SSCER",
          "error": {
              "error": "repository_service_configerror",
              "error_description": "No Record Found! Try Again.."
          }
      }
  ]
}

Incorrect Pan Fetch

{
  "status": "success",
  "statusCode": "200",
  "result": [
      {
          "docId": "001891_PANCR",
          "error": {
              "error": "repository_service_configerror",
              "error_description": "PAN DOB not matched with Aadhaar data"
          }
      }
  ]
}

Invalid Reference ID

{
  "status": "failure",
  "statusCode": "400",
  "error": {
    "code": "ER_INVALID_REFID",
    "message": "Please try verifying the refId"
  }
}

Missing Reference ID

{
  "status": "failure",
  "statusCode": "400",
  "error": {
    "code": "ER_REQ_VALIDATE",
    "message": "referenceId is required"
  }
}

Missing DocID

{
  "status": "failure",
  "statusCode": "400",
  "error": {
    "code": "ER_REQ_VALIDATE",
    "message": "docId is required"
  }
}

All Documents Not Found

{
  "status": "failure",
  "statusCode": "504",
  "result": [
    {
      "uri": "in.gov.transport-DRVLC-UP16202",
      "error": {
        "error": "invalid_uri",
        "error_description": "No file found for given URI"
      }
    },
    {
      "uri": "in.gov.pan-PANCR-KUYPS61",
      "error": {
        "error": "invalid_uri",
        "error_description": "No file found for given URI"
      }
    }
  ]
}

Digilocker Repository Error - 2

{
	"status": "failure",
	"statusCode": "504",
	"error": {
			"code": "ER_DIGILOCKER_REPO_SERVICE_UNPUBLISHED",
			"message": "Error Connecting to digilocker. Please try again after sometime."
		}
}

Digilocker Repository Error - 3

{
	"status": "failure",
	"statusCode": "504",
	"error": {
			"code": "ER_DIGILOCKER_REPO_SERVICE_INACTIVE",
			"message": "Error Connecting to digilocker. Please try again after sometime."
		}
}

Digilocker Repository Error - 4

{
	"status": "failure",
	"statusCode": "504",
	"error": {
			"code": "ER_DIGILOCKER_REPO_SERVICE_CONFIGERROR",
			"message": "Error Connecting to digilocker. Please try again after sometime."
		}
}

Digilocker Repository Error - 5

{
	"status": "failure",
	"statusCode": "504",
	"error": {
			"code": "ER_DIGILOCKER_REPO_SERVICE_RESPERROR",
			"message": "Error Connecting to digilocker. Please try again after sometime."
		}
}

Digilocker Repository Error - 6

{
	"status": "failure",
	"statusCode": "504",
	"error": {
			"code": "ER_DIGILOCKER_REPO_SERVICE_EXCEPTION",
			"message": "Error Connecting to digilocker. Please try again after sometime."
		}
}

Error Response Details

A failure or error response contains an error object within the result array for the specific document ID or URI that failed, or returns a failure status with an error code.
The following table lists all error responses:

Status Code	Error Message	Error Description	Error Resolution
200	No Record Found! Try Again..	The requested document could not be found in the repository. Please verify the document ID and try again.	Verify that the document ID or URI is correct and that the document exists in DigiLocker. Ensure the user has granted proper consent and the document is available in their DigiLocker account.
200	PAN DOB not matched with Aadhaar data	The date of birth associated with the PAN provided does not match the data in the Aadhaar database. Please ensure that the date of birth provided matches the records linked with the Aadhaar number.	Verify that the date of birth matches between PAN and Aadhaar records. Ensure the user's DigiLocker account has the correct Aadhaar-linked information.
400	Please try verifying the refId	You have provided an invalid reference ID. Please verify the reference ID and retry the request.	Verify that the referenceId matches the one used in the DigiLocker Consent Start API request and that it is valid.
400	referenceId is required	The reference ID is a mandatory parameter for this request. Please ensure that you provide a valid reference ID in the request.	Provide a valid referenceId in the request body. The referenceId should be the same one used in the initial DigiLocker consent flow.
400	docId is required	The document ID is a mandatory parameter for this request. Please ensure that you provide a valid document ID in the request.	Provide a valid docId in the request body for non-issued documents. The docId should be in the format orgId_docType.
504	No file found for given URI	The API failed to find the requested document associated with the given URI(s) in the repository. Please verify the URI and retry the request.	Verify that the URI is correct and that the document exists in DigiLocker. Ensure the URI was obtained from a valid issued document fetch operation.
504	Error Connecting to digilocker. Please try again after sometime.	An error occurred while attempting to connect to the Digilocker repository service. Please retry the operation after some time. If the issue persists, please contact the HyperVerge team for further assistance.	Retry the request after some time. If the issue persists, contact the HyperVerge team for resolution. This error may occur due to DigiLocker service unavailability or configuration issues.